package com.ease.util.events {

import flash.events.Event;

[SDK]
/**
 * This class defines a generic method return event that can used by any class to notify
 * its caller through a callback. Examples of its use include a proxy calling back at the
 * completion of a remote method.
 *
 * <p>SDK Version 1.0.0</p>
 */
public class MethodReturnEvent extends Event
{
   private var _result:Object;
   private var _error:Error;
   private var _callContext:Object;
   private var _callee:Object;

   /**
    * This string is used for the <code>type</code> property if no custom id is provided
    * to the constructor.
    */
   public static const DEFAULT_RETURN_ID:String = "methodReturn";

   [Result]
   /**
    * The result or return value from the method invocation whose completion is
    * represented by this event.
    */
   public function get result():Object {
      return _result;
   }

   [Error]
   /**
    * The error resulting from the method invocation whose completion is represented
    * by this event.
    */
   public function get error():Error {
      return _error;
   }

   /**
    * This property represents an arbitrary call context supplied by the caller to the
    * callee when invoking the method whose completion is represented by this event.
    */
   public function get callContext():Object {
      return _callContext;
   }

   /**
    * The callee object is the target of the method invocation whose completion is
    * represented by this event.
    */
   public function get callee():Object {
      return _callee;
   }

   /**
    * Initializes a new instance of this class.
    *
    * @param result
    *    Value for the <code>result</code> property.
    * @param error
    *    Value for the <code>error</code> property.
    * @param callContext
    *    Value for the <code>callContext</code> property.
    * @param callee
    *    Value for the <code>callee</code> property.
    * @param eventId
    *    Value for the <code>type</code> property.
    */
   public function MethodReturnEvent( result:Object, error:Error,
                                      callContext:Object = null, callee:Object = null,
                                      eventId:String = DEFAULT_RETURN_ID ) {
      super( eventId );
      _result = result;
      _error = error;
      _callContext = callContext;
      _callee = callee;
   }

   /**
    * A convenience factory method for this class that assumes null value for the error.
    *
    * @param result
    *    Value for the <code>result</code> property.
    * @param callContext
    *    Value for the <code>callContext</code> property.
    * @param callee
    *    Value for the <code>callee</code> property.
    */
   public static function newResultEvent( result:Object, callContext:Object = null,
                                          callee:Object = null ):MethodReturnEvent {
      return new MethodReturnEvent( result, null, callContext, callee );
   }

   /**
    * A convenience factory method for this class that assumes null value for the result.
    *
    * @param error
    *    Value for the <code>error</code> property.
    * @param callContext
    *    Value for the <code>callContext</code> property.
    * @param callee
    *    Value for the <code>callee</code> property.
    */
   public static function newErrorEvent( error:Error, callContext:Object = null,
                                         callee:Object = null ):MethodReturnEvent {
      return new MethodReturnEvent( null, error, callContext, callee );
   }

   /**
    * Creates a clone of this event. All custom events should override this method.
    *
    * @return
    *    A clone of this event.
    */
   public override function clone():Event {
      return new MethodReturnEvent( result, error, callContext, callee, type );
   }
}

}